Array Functions
| Name | Description | Example |
|---|---|---|
| copy(<array>, <fromIndex>, <toIndex>, <fill>) | Returns a new array with values taken from <array> between index <from> and index <to>. All other values are set to <fill>. The parameters <fromIndex> and <toIndex> must be integers. | copy("Limits: Cash Flow Before Tax", 5, 10, "Inputs: Default Value") |
| cum(<array>) | Returns the (single) cumulative value of <array>. | cum("Volumes: Summary Oil") |
| escalate(<value>, <annualRate>) | Returns an array with <value> escalated by <annualRate>. Here <annualRate> is always regarded as a yearly value. If it is an array instead of a numeric value and the periodicity defined for the project is other than yearly, the value entered for each period is regarded as the yearly rate to be applied during that period. | escalate(1, 0.05) or escalate(1, "Escalation: OpEx Rate") |
| escalateReference(<fromIndex>, <rate>, <logic>) | Returns a reference (escalation factors) by escalating a value of 1 from the period stated in <fromIndex> using the <rate>. The <logic> parameter indicates the behavior for periods before <fromIndex>: setting it to 0 leaves them unescalated (= 1); setting it to 1 performs the inverse escalation for previous values. | escalateReference(5, 0.1, 0) or escalateReference(6, "Escalation: OpEx Rate", 1) |
| firstNegative(<array>[, <defaultValue>]) | Returns the index of the first negative value in <array>. The optional parameter <defaultValue> is the value returned if the function evaluates to undefined (i.e., if no negative values were found). | firstNegative("Limits: Cash Flow Before Tax", 20) |
| firstPositive(<array>[, <defaultValue>]) | Returns the index of the first positive value in <array>. The optional parameter <defaultValue> is the value returned if the function evaluates to undefined (i.e., if no positive values were found). | firstPositive("Limits: Cash Flow Before Tax", 20) |
| firstValue(<array>) | Returns the value of the first index in <array>. | firstValue("Limits: Cash Flow Before Tax") |
| indexGTValue(<array>, <value>, [<defaultindex>]) | Returns the first index of <array> whose value is greater than <value>. The optional parameter <defaultIndex> is the value returned if no index is found. | indexGTValue("Limits: Cum Oil", "Limits: Cum Oil Limit") |
| indexLTValue(<array>, <value>, [<defaultindex>]) | Returns the last index of <array> whose value is less than <value>. The optional parameter <defaultIndex> is the value returned if no index is found. | indexLTValue("Limits: Cum Oil", "Limits: Cum Oil Limit") |
| lastNegative(<array>[, <defaultValue>]) | Returns the index of the last negative value in <array>. The optional parameter <defaultValue> is the value returned if the function evaluates undefined (i.e., if no negative values were found). | lastNegative("Limits: Cash Flow Before Tax", 0) |
| lastPositive(<array>[, <defaultValue>]) | Returns the index of the last positive value in <array>. The optional parameter <defaultValue> is the value returned if the function evaluates to undefined. <defaultValue> is optional (i.e., if no positive values were found). | lastPositive("Limits: Cash Flow Before Tax", 0) |
| lastValue(<array>) | Returns the last value in <array>. | lastValue("Limits: Cash Flow Before Tax") |
| maxValue(<array>) | Returns the maximum value in <array>. | maxValue("Limits: Cash Flow Before Tax") |
| minValue(<array>) | Returns the minimum value in <array>. | minValue("Limits: Cash Flow Before Tax") |
| newArray(<value>) | Returns a new array with <value> in each cell. | newArray(7.62) or newArray("Escalation: OpEx Rate") |
| positionsLeft(<array>, <fill>, <positions>) | Returns a copy of <array> with values pushed <positions> positions to the left. The last <positions> values are set to <fill>. <positions> must be an integer. | positionsLeft("Limits: Cash Flow Before Tax", 0, 3) |
| positionsRight(<array>, <fill>, <positions>) | Returns a copy of <array> with values pushed <positions> positions to the right. The first <positions> values are set to <fill>. <positions> must be an integer. | positionsRight("Limits: Cash Flow Before Tax", 0, 3) |
| previousValue(<array>, <fill>) | Same as shiftRight: returns a copy of <array> with values pushed one position to the right. The first value is set to <fill>. | previousValue("Limits: Cash Flow Before Tax", 0) |
| runningCum(<array>) | Returns an array with the running cumulative of <array>, i.e. the separate cumulative values of <array> for each period. | runningCum("Volumes: Summary Oil") |
| shiftLeft(<array>, <fill>) | Returns a copy of <array> with values pushed one position to the left. The last value is set to <fill>. | shiftLeft("Limits: Cash Flow Before Tax", 0) |
| shiftRight(<array>, <fill>) | Same as previousValue: returns a copy of <array> with values pushed one position to the right. The first value is set to <fill>. | shiftRight("Limits: Cash Flow Before Tax", 0) |
| valueAtIndex(<array>, <index>) | Returns the value of <array> at <index>. | valueAtIndex("Limits: Cash Flow Before Tax", "Limits: Base Year") |
Array functions that return a single value are excluded from the Functions list in PetroVR Plan, but are available in PetroVR Econ: they are cum, firstPositive, lastPositive, firstNegative, lastNegative, firstValue, lastValue, minValue, maxValue, valueAtIndex, indexGTValue and indexLTValue. This is so because in Plan it is preferable to simply use the current values (i.e., values at the current step of the simulation) of runtime variables instead of reading them from a list or array.
A typical example of the use of these functions in an Econ model:
valueAtIndex ("Production_Facility_FacilityName_Oil_Rates", Period Number)
This returns the oil rate during a specific period in the history of the facility. Even if the valueAtIndex function is not provided by the Plan Function Editor, you could still type the equivalent formula in Plan:
valueAtIndex ("Production_Facility_FacilityName_Oil_Rates", "Pvr: Run Time: Current Period")
But the best way to obtain this value is simply to use the variable name:
"Facility: FacilityName: Run Time: Oil: Rate"
which returns the current rate (i.e., the rate at the current step of the simulation).
The escalate function had historically been calculated using an approximation when the periodicity is not years. From PetroVR v13.2 (2018) on, the accuracy of escalate has been improved. In the past PetroVR used an easy to compute approximation for the nth root of (1 + annualRate). This has been replaced with the proper value. Because of this improvement, models migrated from earlier versions of the product that used the escalate function with non-yearly periodicities could show small differences in their results.